/*
 * Copyright 2010 Biz-e (info@biz-e.nl)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package nl.biz_e.acl.client;

import java.util.List;

import nl.biz_e.acl.shared.model.Authorization;
import nl.biz_e.acl.shared.model.Context;
import nl.biz_e.acl.shared.model.User;
import nl.biz_e.acl.shared.model.UserGroup;

import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * Handles all server side authorization logic.
 * 
 * @author Joost A. Bloemsma
 * 
 */
@RemoteServiceRelativePath("authorization")
public interface AuthorizationService extends RemoteService {

    /**
     * Returns {@code true} if the passed user is auhtorized for the passed
     * context
     * 
     * @param user
     * @param ctx
     * @return true if authorized, otherwise false
     */
    public Boolean isAuthorized(User user, Context ctx);

    /**
     * Returns {@code true} if the passed usergroup is auhtorized for the passed
     * context
     * 
     * @param group
     * @param ctx
     * @return true if authorized, otherwise false
     */
    public Boolean isAuthorized(UserGroup group, Context ctx);

    /**
     * Returns a list of all user authorized for the passed context
     * 
     * @param ctx
     * @return a list of users
     */
    public List<User> getAuthorizedUsers(Context ctx);

    /**
     * Returns a list of all usergroups authorized for the passed context
     * 
     * @param ctx
     * @return a list of usergroups
     */
    public List<UserGroup> getAuthorizedGroups(Context ctx);

    /**
     * Authorizes (or revokes) a user for a certain context
     * 
     * @param user
     * @param ctx
     * @param approved
     *            true if the user should be allowed, false for revoked.
     */
    public void setAuthorization(User user, Context ctx, boolean approved);

    /**
     * Authorizes (or revokes) a usergroup for a certain context
     * 
     * @param group
     * @param ctx
     * @param approved
     *            true if the group should be allowed, false for revoked.
     */
    public void setAuthorization(UserGroup group, Context ctx, boolean approved);

    /**
     * Returns an {@link Authorization} instance describing the authorization of
     * the passed user for the passed context.
     * 
     * @param user
     * @param ctx
     * @return {@link Authorization} instance
     */
    public Authorization getAuthorization(User user, Context ctx);

    /**
     * Returns an {@link Authorization} instance describing the authorization of
     * the passed group for the passed context.
     * 
     * @param group
     * @param ctx
     * @return {@link Authorization} instance
     */
    public Authorization getAuthorization(UserGroup group, Context ctx);

    /**
     * Returns all Authorizations for the passed user
     * 
     * @param user
     * @return a list of {@link Authorization} instances
     */
    public List<Authorization> getAuthorizations(User user);

    /**
     * Returns all Authorizations for the passed usergroup
     * 
     * @param group
     * @return a list of {@link Authorization} instances
     */
    public List<Authorization> getAuthorizations(UserGroup group);

    /**
     * Returns all Authorizations for the passed context
     * 
     * @param ctx
     * @return a list of {@link Authorization} instances
     */
    public List<Authorization> getAuthorizations(Context ctx);

    /**
     * Deletes the passed authorization.<br/>
     * <h3>Note:</h3> This is not the same as revoking a user or grop for a
     * certain context. It only removes the rule for this specific
     * user(group)/context combination
     * 
     * @param authorization
     */
    public void deleteAuthorization(Authorization authorization);

    /**
     * Deletes the authorization rule for the passed user/context combination.
     * 
     * @param user
     * @param ctx
     */
    public void deleteAuthorization(User user, Context ctx);

    /**
     * Deletes the authorization rule for the passed usergroup/context
     * combination.
     * 
     * @param group
     * @param ctx
     */
    public void deleteAuthorization(UserGroup group, Context ctx);
}
